130 MIDI Tool Box/130 MIDI Tool Box.iso/midimod1/mod-form.txt

Text File | 1993-04-10 | 15KB | 304 lines

Noisetracker/Soundtracker/Protracker Module Format
--------------------------------------------------
Credits: Norman Lin, Mark Cox, Lars Hamre, Peter Hanning
(All numbers below are given in decimal)

Module Format:
# Bytes      Description
-------      -----------
20           The module's title, padded with null (\0) bytes.

(Data repeated for each sample 1-15 or 1-31:)
22           Sample's name, padded with null bytes.
2            Sample length in words (ie. multiply by 2 for length in bytes).
1            Lowest four bits represent a signed nibble (-8..7) which is
             the finetune value for the sample. It is mostly ignored, but I
             think each note is supposed to be 16 "finetunes" from the next.
1            Volume of sample. Legal values are 0..64.
2            Start of sample repeat offset in words.
2            Length of sample repeat in words ( >1 if looping is used)
(End of this sample's data.. each sample uses the same format and they are
 stored sequentially)
NB. All 2 byte lengths are stored with the Hi-byte first, as is usual on
    the Amiga.

1            Number of song positions (ie. number of patterns played
             throughout the song). Legal values are 1..128.
1            Historically set to 127, but can be safely ignored. Noisetracker
             uses this byte to indicate restart position - this has been
             made redundant by the 'Position Jump' effect.
128          Pattern table: patterns to play in each song position (0..127).
             Each byte has a legal value of 0..63. The highest value in this
             table is the highest pattern stored, no patterns above this
             value are stored.
(4)          The four letters "M.K." These are the initials of Mahoney &
             Kaktus and were introduced along with the increase to 31
             samples. Startrekker puts "FLT4" or "FLT8" here to indicate
             the # of channels. If no letters are here, then this is the
             start of the pattern data, and only 15 samples are present.

(Data repeated for each pattern:)
1024         Pattern data for each pattern (starting at 0).
(Each pattern has same format and is stored in numerical order.
 See below for pattern format)

(Data repeated for each sample:)
xxxxxx       Each sample is stored as a collection of bytes (length of
             a sample was given previously in the module). Each byte is
             a signed value (-128..127) which is the channel data. When
             a sample is played at a pitch of C2, 8000 bytes of channel
             data are sent to the channel per second. Multiply the rate
             by the twelfth root of 2 for each semitone increase in pitch
             eg. moving the pitch up 1 octave doubles the rate. The data
             is stored in the order it is played (eg. first byte is first
             byte played), but if the 'invert loop' effect is used then
             it order is reversed.
(Each sample is stored sequentially)

Pattern Format:
Each pattern is divided into 64 divisions. By allocating different tempos
for each pattern and spacing the notes across different amounts of divisions,
different bar sizes can be accomodated.

Each division contains the data for each channel (1..4) stored after each
other. Each channel's data in the division has an identical format which
consists of 2 words (4 bytes). Divisions are numbered 0..63. Each division
may be divided into a number of ticks (see 'set speed' effect below).

Channel Data:
                   (the four bytes of channel data in a pattern divison)
7654-3210 7654-3210 7654-3210 7654-3210
wwww xxxxxxxxxxxxxx yyyy zzzzzzzzzzzzzz

    wwwwyyyy (8 bits) is the sample for this channel/division (0 = no sample)
xxxxxxxxxxxx (12 bits) is the sample's period (or effect parameter)
zzzzzzzzzzzz (12 bits) is the effect for this channel/division

If there is to be no new sample to be played at this division on this
channel, then the old sample on this channel will continue, or at least be
"remembered" for any effects. Only one sample may play on a channel at a
time, so playing a new sample will cancel an old one - even if there has
been no data supplied for the new sample. Though, if you are using a
"silence" sample (ie. no data, only used to turn off other samples) it is
polite to set its default volume to 0.

To determine what pitch the sample is to be played on, look up the period
in a table, such as the one below. It is best to do a binary-search,
especially if you plan to use periods outside the "standard" range. Periods
are the internal representation of the pitch, so effects that alter pitch
(eg. sliding) alter the period value (see "effects" below).

          C    C#   D    D#   E    F    F#   G    G#   A    A#   B
Octave 1: 856, 808, 762, 720, 678, 640, 604, 570, 538, 508, 480, 453
Octave 2: 428, 404, 381, 360, 339, 320, 302, 285, 269, 254, 240, 226
Octave 3: 214, 202, 190, 180, 170, 160, 151, 143, 135, 127, 120, 113

Octave 0:1712,1616,1525,1440,1357,1281,1209,1141,1077,1017, 961, 907,
Octave 4: 107, 101,  95,  90,  85,  80,  76,  71,  67,  64,  60,  57

(Octaves 0 and 4 are NOT standard, so don't rely on every tracker being
 able to play them, or even not crashing if being given them - it's just
 nice that if you can code it, to allow them to be read.)

Effects:
Effects are written as groups of 4 bits, eg. 1871 = 7 * 256 + 4 * 16 + 15
= [7][4][15]. The high nibble (4 bits) usually determines the
effect, but if it is [14], then the second nibble is used as well.

[0]: Arpeggio
  Where [0][x][y] means "play note, note+x semitones, note+y semitones, then
  return to original note". The fluctuations are carried out evenly spaced
  in one pattern division. They are usually used to simulate chords, but
  this doesn't work too well. They are also used to produce heavy vibrato.
  A major chord is when x=4, y=7. A minor chord is when x=3, y=7.

[1]: Slide up
  Where [1][x][y] means "smoothly decrease the period of current sample
  by x*16+y after each tick in the division". The ticks/division are set
  with the 'set speed' effect (see below). If the period of the note being
  played is z, then the final period will be z - (x*16 + y)*(ticks - 1).
  As the slide rate depends on the speed, changing the speed will change
  the slide. You cannot slide beyond the note B3 (period 113).

[2]: Slide down
  Where [2][x][y] means "smoothly increase the period of current sample
  by x*16+y after each tick in the division". Similar to [1], but lowers
  the pitch. You cannot slide beyond the note C1 (period 856).

[3]: Slide to note
  Where [3][x][y] means "smoothly change the period of current sample by
  x*16+y after each tick in the division, never sliding beyond current
  period". The period-length in this channel's division is a parameter to
  this effect, and hence is not played. Sliding to a note is similar to
  effects [1] and [2], but the slide will not go beyond the given period,
  and the direction is implied by that period. If [x] and [y] are both 0,
  then the old slide will continue.

[4]: Vibrato
  Where [4][x][y] means "oscillate the sample pitch using a particular
  waveform with amplitude y/16 semitones, such that (x * ticks)/64 cycles
  occur in the division". The waveform is set using effect [14][4]. By
  placing vibrato effects on consecutive divisions, the vibrato effect
  can be maintained. If either [x] or [y] are 0, then the old vibrato
  values will be used.

[5]: Continue 'Slide to note', but also do Volume slide
  Where [5][x][y] means "either slide the volume up x*5 or slide the volume
  down y*5, at the same time as continuing the last 'Slide to note'". It is
  illegal for both x and y to be non-zero. You cannot slide outside the
  volume range 0..64. The period-length in this channel's division is a
  parameter to this effect, and hence is not played.

[6]: Continue 'Vibrato', but also do Volume slide
  Where [6][x][y] means "either slide the volume up x*5 or slide the volume
  down y*5, at the same time as continuing the last 'Vibrato'". It is
  illegal for both x and y to be non-zero. You cannot slide outside the
  volume range 0..64.

[7]: Tremolo
  Where [7][x][y] means "oscillate the sample volume using a particular
  waveform with amplitude y*5, such that (x * ticks)/64 cycles occur in the
  division". The waveform is set using effect [14][7]. Similar to [4].

[8]: -- Unused --

[9]: Set sample offset
  Where [9][x][y] means "play the sample from offset x*4096 + y*256".
  The offset is measured in words. If no sample is given, yet one is still
  playing on this channel, it should be retriggered to the new offset using
  the current volume.

[10]: Volume slide
  Where [10][x][y] means "either slide the volume up x*5 or slide the
  volume down y*5". It is illegal for both x and y to be non-zero. You
  cannot slide outside the volume range 0..64.

[11]: Position Jump
  Where [11][x][y] means "stop the pattern after this division, and
  continue the song at song-position x*16+y". This shifts the 'pattern-
  cursor' in the pattern table (see above). Legal values for x*16+y are
  from 0 to 127.

[12]: Set volume
  Where [12][x][y] means "set current sample's volume to x*16+y". Legal
  volumes are 0..64.

[13]: Pattern Break
  Where [13][x][y] means "stop the pattern after this division, and continue
  the song at the next pattern at division x*16+y". Legal divisions are
  from 0 to 63.

[14][0]: Set filter on/off
  Where [14][0][x] means "set sound filter ON if x is 1, and OFF is x is 0".
  This is a hardware command for some Amigas, so if you don't understand
  it, it is better not to use it.

[14][1]: Fineslide up
  Where [14][1][x] means "decrement the period of the current sample by x".
  The incrementing takes place at the beginning of the division, and hence
  there is no sliding. You cannot slide beyond the note B3 (period 113).

[14][2]: Fineslide down
  Where [14][2][x] means "increment the period of the current sample by x".
  Similar to [14][1] but shifts the pitch down. You cannot slide beyond the
  note C1 (period 856).

[14][3]: Set glissando on/off
  Where [14][3][x] means "set glissando ON if x is 1, OFF is x is 0". Used
  in conjunction with [3] ('Slide to note'). If glissando is on, then
  'Slide to note' will slide in semitones, otherwise will perform the
  default smooth slide.

[14][4]: Set vibrato waveform
  Where [14][4][x] means "set the waveform of succeeding 'vibrato' effects
  to wave #x". [4] is the 'vibrato' effect.  Possible values for x are:
    0 - sine (default)      /\    /\     (2 cycles)
    4  (without retrigger)     \/    \/

    1 - ramp down          | \   | \
    5  (without retrigger)     \ |   \ |

    2 - square             ,--,  ,--,
    6  (without retrigger)    '--'  '--'

    3 - random
    7  (without retrigger)
  Sorry, don't ask me what the "without retrigger" means.

[14][5]: Set finetune value
  Where [14][5][x] means "sets the finetune value of the current sample
  to the signed nibble x". x has legal values of 0..15, corresponding to
  signed nibbles 0..-1.

[14][6]: Loop pattern
  Where [14][6][x] means "set the start of a loop to this division if x
  is 0, otherwise after this division, jump back to the start of a loop
  and play it another x times before continuing". If the start of the loop
  was not set, it will default to the start of the current pattern. Hence
  'loop pattern' cannot be performed across multiple patterns. Note that
  loops do not support nesting, and you may generate an infinite loop
  if you try to nest 'loop pattern's.

[14][7]: Set tremolo waveform
  Where [14][7][x] means "set the waveform of succeeding 'tremolo' effects
  to wave #x". Similar to [14][4], but alters effect [7] - the 'tremolo'
  effect.

[14][8]: -- Unused --

[14][9]: Retrigger sample
  Where [14][9][x] means "trigger current sample every x ticks in this
  division". If x is 0, then no retriggering is done (acts as if no
  effect was chosen), otherwise the retriggering begins on the first tick
  and then x ticks after that, etc.

[14][10]: Fine volume slide up
  Where [14][10][x] means "increment the volume of the current sample by x".
  The incrementing takes place at the beginning of the division, and hence
  there is no sliding. You cannot slide beyond volume 64.

[14][11]: Fine volume slide down
  Where [14][11][x] means "decrement the volume of the current sample by x".
  Similar to [14][10] but lowers volume. You cannot slide beyond volume 0.

[14][12]: Cut sample
  Where [14][12][x] means "after the current sample has been played for
  x ticks in this division, its volume will be set to 0". This implies
  that if x is 0, then you will not hear any of the sample. If you wish
  to insert "silence" in a pattern, it is better to use a "silence"-sample
  (see above) due to the lack of proper support for this effect.

[14][13]: Delay sample
  Where [14][13][x] means "do not start this division's sample for the
  first x ticks in this division, play the sample after this". This
  implies that if x is 0, then you will hear no delay. Note that this
  effect only influences a sample if it was started in this division.

[14][14]: Delay pattern
  Where [14][14][x] means "after this division, the pattern will not be
  played for the length of x notes, resume the pattern after this".

[14][15]: Invert loop
  Where [14][15][x] means "if x is greater than 0, then play the current
  sample's loop backwards at speed x, otherwise play the sample forward".
  It will only work if the sample's loop (defined previously) is not too
  big.

[15]: Set speed
  Where [15][x][y] means "set speed to x*16+y". Though it is not that
  simple. Let z = x*16+y. z=0 is the same as z=1. If z<32 then it means
  "set ticks/division to z and beats/min to 768/z" otherwise it means "set
  beats/min to z". Default values are 6 ticks/division, and 128 beats/min
  (4 divisions = 1 beat). It is best to not mix the different types of
  "set speed" as I have seen 4 different trackers act 4 different ways
  when mixing them.

NB. I have tested most of the effects, but some were a bit hard to test
(such as filter, etc.) It is probably better to use this document as a
guide rather than as a hard-and-fast definition of the module format.
Oh.. and yes, I would normally give bytes as hex values, but it is easier
to understand a consistant notation.

Andrew Scott (Adrenalin Software), INTERNET:[e-mail]
Author of MIDIMOD.